Docker Compose 및 외부 Nginx 리버스 프록시를 활용한 프로덕션급 Nextcloud Hub 배포 안내서

1. 아키텍처 고려사항

1.1 목표 개요

본 보고서의 주요 목표는 이미 Nginx 리버스 프록시와 SSL이 구성된 인프라에 Docker Compose를 사용하여 안전하고 확장 가능하며 성능이 뛰어난 Nextcloud Hub 인스턴스를 배포하는 방법을 제시하는 것입니다. 이 과정에서 프로덕션 환경에 적합한 안정성, 데이터 영속성, 그리고 운영 모범 사례에 중점을 둡니다.

1.2 배포 모델 분석: 마이크로서비스 vs. 올인원(AIO)

Nextcloud를 Docker로 배포할 때는 두 가지 공식 지원 경로가 존재하며, 각기 다른 철학을 가지고 있습니다.1 배포에 앞서 이 두 모델의 장단점을 이해하고 자신의 요구사항에 맞는 아키텍처를 선택하는 것이 매우 중요합니다.

마이크로서비스 접근 방식: 이 모델은 Nextcloud 애플리케이션, 데이터베이스, 캐시 등 각 구성 요소를 개별 컨테이너로 분리하여 docker-compose.yml 파일에 명시적으로 정의합니다.3 이 방식은 시스템의 모든 요소를 세밀하게 제어할 수 있는 최대의 유연성을 제공합니다. 공식 Nextcloud Docker 이미지는 “커뮤니티 자원봉사자들이 유지 관리하며 전문가용으로 설계되었다“고 명시되어 있어, 사용자의 높은 전문성을 요구하는 대신 높은 자유도를 보장합니다.2
올인원(AIO) 접근 방식: 이 모델은 Nextcloud GmbH에서 직접 관리하며 “공식 Nextcloud 설치 방법“으로 소개됩니다.1 단일 ‘마스터’ 컨테이너가 Nextcloud Hub 운영에 필요한 모든 백엔드 컨테이너(Nextcloud, Office, Talk 백엔드 등)의 생성, 관리, 업데이트를 자동으로 처리합니다.5 이 방식은 유지보수를 간소화하고, 별도의 복잡한 설정 없이도 Hub의 모든 기능을 즉시 사용할 수 있도록 보장합니다.6

이 두 모델의 선택은 단순히 기술적인 선호도를 넘어, 장기적인 운영 및 유지보수 전략에 영향을 미칩니다. Nextcloud GmbH가 커뮤니티 기반의 마이크로서비스 이미지보다 AIO 모델을 공식적으로 강력하게 지지하는 것은 중요한 전략적 변화를 시사합니다.2 이는 모든 Hub 기능이 활성화된 일관된 사용자 경험을 보장하고 지원 부담을 줄일 수 있는, 보다 통합되고 어플라이언스와 유사한 배포 모델로 나아가고 있음을 보여줍니다. 따라서 마이크로서비스 경로를 선택하는 것은 구성 요소 통합과 장기 유지보수에 대한 더 큰 책임을 감수하는 것을 의미하며, AIO 경로는 일부 제어권을 포기하는 대신 운영 단순성과 공식 지원에 가까운 경험을 얻는 것을 의미합니다.

표 1: Nextcloud 배포 모델 비교

요소	마이크로서비스 스택	올인원(AIO) 스택
제어 세분성	높음. 각 컴포넌트(DB, Redis 등)의 버전과 설정을 개별적으로 완벽하게 제어.	낮음. AIO 마스터 컨테이너가 최적화된 버전의 컴포넌트를 자동으로 관리.
초기 설정 용이성	중간. `docker-compose.yml` 파일과 환경 변수에 대한 이해 필요.	높음. 단일 `docker run` 명령과 웹 기반 설정 마법사를 통해 간편하게 설치.
업데이트 및 유지보수	수동. 사용자가 직접 `docker compose pull` 명령으로 각 이미지를 업데이트하고 호환성 확인 필요.	자동화. AIO 관리 인터페이스에서 클릭 한 번으로 모든 컨테이너를 안전하게 업데이트.
통합 기능	기본 Nextcloud만 설치. Office, Talk 고성능 백엔드 등은 수동으로 추가 설정 필요.	Nextcloud Office, Talk 고성능 백엔드, 백업 솔루션 등 Hub의 핵심 기능이 기본 포함.6
리소스 오버헤드	상대적으로 낮음. 필요한 최소한의 컨테이너만 실행.	상대적으로 높음. 다양한 부가 기능 컨테이너가 함께 실행될 수 있음.
문제 해결 투명성	높음. 각 컨테이너의 로그를 직접 확인하고 문제를 진단하기 용이.	중간. AIO 인터페이스가 로그를 제공하지만, 내부 동작이 추상화되어 있음.
공식 지원 수준	커뮤니티 기반 지원. 전문 사용자를 대상으로 함.2	Nextcloud GmbH에서 공식적으로 권장하는 설치 방법.5

1.3 권장 스택 구성 요소

어떤 배포 모델을 선택하든, 프로덕션 환경에서는 다음과 같은 구성 요소를 사용하는 것이 강력히 권장됩니다.

데이터베이스: 기본값인 SQLite나 MariaDB 대신 PostgreSQL 사용을 권장합니다. PostgreSQL은 대규모 동시 접속 환경에서의 강력한 성능, 데이터 무결성 기능, 안정성으로 인해 프로덕션급 Nextcloud 인스턴스에 가장 이상적인 선택입니다.4
캐시: Redis는 두 가지 중요한 역할을 수행합니다. 첫째, 인메모리 캐싱을 통해 Nextcloud의 UI 반응 속도와 전반적인 성능을 향상시킵니다. 둘째, 여러 사용자가 동시에 파일에 접근할 때 발생할 수 있는 데이터 손상을 방지하기 위한 트랜잭션 파일 잠금(Transactional File Locking)에 필수적입니다.3 공식 문서에서도 Redis 사용을 강력히 권장합니다.9

2. 배포 모델 I: 마이크로서비스 스택

이 섹션에서는 유연성과 제어권을 우선시하는 사용자를 위해 마이크로서비스 스택을 구성하는 방법을 상세히 설명합니다.

2.1 디렉터리 구조 및 환경 설정

체계적인 관리를 위해 프로젝트 디렉터리 구조를 생성하는 것이 좋습니다. 예를 들어, /opt/stacks/nextcloud/와 같은 경로를 생성하여 docker-compose.yml 파일과 환경 변수 파일을 함께 보관합니다.10

데이터베이스 암호와 같은 민감한 정보는 버전 관리 시스템에 포함될 수 있는 docker-compose.yml 파일에서 분리하여 .env 파일에 저장하는 것이 보안상 안전합니다.10 아래는

.env 파일의 예시입니다.

.env 파일 예시 (/opt/stacks/nextcloud/.env)

코드 스니펫

# PostgreSQL 설정
POSTGRES_DB=nextcloud
POSTGRES_USER=nextcloud
POSTGRES_PASSWORD=매우_강력한_데이터베이스_비밀번호

# 초기 Nextcloud 관리자 계정 설정
NEXTCLOUD_ADMIN_USER=admin
NEXTCLOUD_ADMIN_PASSWORD=매우_강력한_관리자_비밀번호

# PHP 업로드 및 메모리 제한
PHP_MEMORY_LIMIT=1024M
PHP_UPLOAD_LIMIT=10G

# Apache 업로드 제한 (PHP_UPLOAD_LIMIT과 일치시키는 것을 권장)
APACHE_BODY_LIMIT=10737418240

2.2 docker-compose.yml 구성 파일

다음은 Nextcloud 애플리케이션, PostgreSQL 데이터베이스, Redis 캐시를 포함하는 프로덕션 환경에 적합한 docker-compose.yml 파일입니다. 각 서비스와 설정에 대한 설명이 주석으로 포함되어 있습니다.

docker-compose.yml 파일 (/opt/stacks/nextcloud/docker-compose.yml)

YAML

version: '3.8'

services:
# Nextcloud 애플리케이션 서비스
app:
image: nextcloud:apache
container_name: nextcloud-app
restart: unless-stopped
networks:
- nextcloud_network
depends_on:
- db
- redis
volumes:
# Named Volume을 사용하여 Nextcloud의 핵심 데이터를 영속적으로 저장
- nextcloud_html:/var/www/html
- nextcloud_apps:/var/www/html/custom_apps
- nextcloud_config:/var/www/html/config
- nextcloud_data:/var/www/html/data
environment:
#.env 파일에서 데이터베이스 연결 정보 참조
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
- POSTGRES_HOST=db
# Redis 연결 정보
- REDIS_HOST=redis
# 초기 관리자 계정 정보
- NEXTCLOUD_ADMIN_USER=${NEXTCLOUD_ADMIN_USER}
- NEXTCLOUD_ADMIN_PASSWORD=${NEXTCLOUD_ADMIN_PASSWORD}
# 신뢰할 수 있는 도메인 (초기 설정용, 추후 config.php에서 관리)
- NEXTCLOUD_TRUSTED_DOMAINS=nextcloud.example.com
# 리버스 프록시 환경 변수
- TRUSTED_PROXIES=nginx_proxy_ip_or_range # Nginx 프록시의 IP 주소 또는 CIDR 범위
- OVERWRITEPROTOCOL=https
- OVERWRITEHOST=nextcloud.example.com
# PHP 및 Apache 설정
- PHP_MEMORY_LIMIT=${PHP_MEMORY_LIMIT}
- PHP_UPLOAD_LIMIT=${PHP_UPLOAD_LIMIT}
- APACHE_BODY_LIMIT=${APACHE_BODY_LIMIT}

# PostgreSQL 데이터베이스 서비스
db:
image: postgres:16-alpine
container_name: nextcloud-db
restart: unless-stopped
networks:
- nextcloud_network
volumes:
# 데이터베이스 데이터를 영속적으로 저장
- db_data:/var/lib/postgresql/data
environment:
#.env 파일에서 데이터베이스 생성 정보 참조
- POSTGRES_DB=${POSTGRES_DB}
- POSTGRES_USER=${POSTGRES_USER}
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

# Redis 캐시 서비스
redis:
image: redis:alpine
container_name: nextcloud-redis
restart: unless-stopped
networks:
- nextcloud_network
volumes:
# Redis 데이터를 영속적으로 저장 (선택 사항)
- redis_data:/data

# 컨테이너 간 통신을 위한 네트워크 정의
networks:
nextcloud_network:
driver: bridge

# 데이터 영속성을 위한 볼륨 정의
volumes:
nextcloud_html:
nextcloud_apps:
nextcloud_config:
nextcloud_data:
db_data:
redis_data:

2.3 설정의 생명주기:.env 파일과 config.php의 관계

Nextcloud Docker 환경에서 반드시 이해해야 할 중요한 운영상의 특징이 있습니다. docker-compose.yml이나 .env 파일에 정의된 환경 변수들(POSTGRES_DB, NEXTCLOUD_ADMIN_USER 등)은 컨테이너가 최초로 시작될 때 Nextcloud를 설치하고 초기화하는 데에만 사용됩니다.8 이 초기화 과정에서

/var/www/html/config/config.php 파일이 생성되며, 이 파일에 모든 설정값이 기록됩니다.

일단 config.php 파일이 생성되고 나면, Nextcloud 애플리케이션은 더 이상 환경 변수를 참조하지 않고 오직 config.php 파일의 내용만을 신뢰할 수 있는 단일 정보 소스(Single Source of Truth)로 사용합니다. 컨테이너의 시작 스크립트는 config.php 파일의 존재 여부를 확인하고, 파일이 있으면 설치 과정을 건너뛰고 바로 애플리케이션을 실행합니다.

이것이 의미하는 바는 매우 중요합니다. 예를 들어, 나중에 신뢰할 수 있는 프록시 IP를 변경하기 위해 .env 파일을 수정하고 docker compose restart 명령을 실행해도 Nextcloud 설정에는 아무런 변화가 없습니다. 이러한 변경 사항을 적용하려면 반드시 컨테이너에 접속하여 occ 명령줄 도구를 사용하거나, /var/www/html/config/config.php 파일을 직접 수정해야 합니다. 이 동작 방식을 이해하지 못하면 설정 변경이 적용되지 않는 문제로 인해 상당한 혼란을 겪을 수 있습니다.3

2.4 스택 초기화 및 검증

구성 파일 작성이 완료되면 다음 명령을 사용하여 Nextcloud 스택을 시작합니다. -d 옵션은 컨테이너를 백그라운드에서 실행하도록 합니다.10

Bash

cd /opt/stacks/nextcloud/
docker compose up -d

스택이 정상적으로 실행되고 있는지 확인하려면 다음 명령을 사용합니다.

컨테이너 상태 확인: docker compose ps
Nextcloud 앱 로그 확인: docker compose logs -f app (초기화 과정을 모니터링할 수 있습니다.)

3. Nginx 리버스 프록시 및 애플리케이션 통합

이 섹션에서는 기존에 운영 중인 Nginx 리버스 프록시와 새로 배포된 Nextcloud Docker 컨테이너를 연동하는 방법을 설명합니다.

3.1 Nginx `server` 블록 구성

Nginx 설정 디렉터리(예: /etc/nginx/sites-available/)에 Nextcloud 도메인을 위한 새로운 설정 파일을 생성합니다. 아래는 프로덕션 환경에 권장되는 Nginx server 블록 구성의 예시입니다.

Nginx 설정 파일 예시 (/etc/nginx/sites-available/nextcloud.example.com.conf)

Nginx

# 업스트림 정의: Nextcloud 앱 컨테이너를 가리킴
# docker-compose.yml에서 포트를 노출하지 않았으므로,
# Nginx와 Nextcloud 컨테이너를 동일한 Docker 네트워크에 연결해야 함.
# 또는, docker-compose.yml의 app 서비스에 ports: - "127.0.0.1:8080:80"을 추가하고
# 아래 서버 주소를 http://127.0.0.1:8080; 으로 설정할 수 있음.
# 이 예시에서는 Nginx와 Nextcloud가 'nextcloud_network'에 함께 있다고 가정.
upstream nextcloud_upstream {
server nextcloud-app:80;
}

# HTTP 요청을 HTTPS로 리디렉션
server {
listen 80;
server_name nextcloud.example.com;
return 301 https://$server_name$request_uri;
}

# HTTPS 서버 블록
server {
listen 443 ssl http2;
server_name nextcloud.example.com;

# SSL 인증서 경로 (사용자 환경에 맞게 수정)
ssl_certificate /etc/letsencrypt/live/nextcloud.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/nextcloud.example.com/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

# 보안 헤더
add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-Frame-Options "SAMEORIGIN" always;
add_header Referrer-Policy "no-referrer" always;

location / {
proxy_pass http://nextcloud_upstream;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;

# 대용량 파일 업로드 설정
client_max_body_size 10G;
}

# CalDAV 및 CardDAV 서비스 검색을 위한 리디렉션
location /.well-known/carddav {
return 301 $scheme://$host/remote.php/dav;
}
location /.well-known/caldav {
return 301 $scheme://$host/remote.php/dav;
}
}

3.2 다층적 파일 업로드 제한 설정

Nextcloud에서 대용량 파일 업로드를 성공적으로 활성화하려면 스택의 여러 독립적인 계층에서 제한을 일관되게 설정해야 합니다. 어느 한 계층이라도 설정이 누락되면 업로드는 더 낮은 제한값에 맞춰 실패하게 됩니다.

Nginx 리버스 프록시 계층: 사용자의 요청을 가장 먼저 받는 Nginx는 client_max_body_size 지시어를 통해 요청 본문의 최대 크기를 제한합니다. 이 값을 원하는 업로드 한계(예: 10G)로 설정해야 합니다.12
웹 서버(Apache) 계층: Nginx를 통과한 요청은 nextcloud:apache 컨테이너 내부의 Apache 웹 서버로 전달됩니다. 이 컨테이너는 APACHE_BODY_LIMIT 환경 변수를 통해 Apache의 업로드 제한을 제어합니다. 이 값은 바이트 단위로 설정해야 합니다.9
PHP 처리 계층: 마지막으로 Apache는 요청을 PHP 프로세스에 넘깁니다. PHP는 자체적으로 post_max_size와 upload_max_filesize 설정을 가지고 있습니다. Nextcloud 이미지는 이 두 설정을 PHP_UPLOAD_LIMIT 환경 변수 하나로 편리하게 제어할 수 있도록 제공합니다.2

결론적으로, 실제 적용되는 업로드 한도는 이 세 가지 설정값 중 가장 작은 값이 됩니다. 따라서 성공적인 대용량 파일 업로드를 위해서는 .env 파일의 PHP_UPLOAD_LIMIT 및 APACHE_BODY_LIMIT 값과 Nginx 설정의 client_max_body_size 값을 모두 원하는 최대 크기로 동일하게 설정하는 것이 필수적입니다.

3.3 CalDAV/CardDAV 서비스 검색

캘린더나 주소록 클라이언트 애플리케이션은 .well-known URL을 사용하여 서버 설정을 자동으로 검색합니다. Nextcloud가 리버스 프록시 뒤에서 실행될 때, 이 자동 검색이 올바르게 작동하려면 프록시 서버가 직접 리디렉션을 처리해야 합니다. 위 Nginx 설정 예시에 포함된 것처럼, /.well-known/caldav와 /.well-known/carddav 경로에 대한 요청을 Nextcloud의 DAV 엔드포인트인 /remote.php/dav로 301 리디렉션하도록 설정해야 합니다.11

3.4 Nextcloud의 프록시 설정 최종화 (config.php)

초기 실행 후, 생성된 config.php 파일을 수정하여 Nextcloud가 리버스 프록시를 신뢰하고 올바른 URL을 생성하도록 설정해야 합니다.

먼저, 다음 명령으로 Nextcloud 앱 컨테이너의 셸에 접속합니다.

Bash

docker compose exec -u www-data app bash

그 다음, 텍스트 편집기(예: nano 또는 vi)를 사용하여 /var/www/html/config/config.php 파일을 엽니다.

파일 내의 $CONFIG 배열에 다음 항목들을 추가하거나 수정합니다.

trusted_domains: 배열에 외부에서 접속할 공개 도메인 이름(예: nextcloud.example.com)을 추가합니다.3
trusted_proxies: Nginx 프록시 서버의 IP 주소를 배열에 추가합니다. Docker와 Nginx가 동일한 호스트에 있다면, Docker의 게이트웨이 IP(예: 172.18.0.1)가 될 수 있습니다. 이 IP는 docker network inspect nextcloud_network 명령으로 확인할 수 있습니다.11
overwrite 매개변수: 프록시를 통해 접속할 때 Nextcloud가 올바른 URL(프로토콜, 호스트명 등)을 생성하도록 강제하는 설정입니다. 이는 알림, 공유 링크 등이 올바르게 작동하는 데 필수적입니다.8

config.php 수정 예시:

PHP

<?php
$CONFIG = array (
//... 기존 설정들...
'trusted_domains' =>
array (
0 => 'localhost', // 필요 시 유지
1 => 'nextcloud.example.com',
),
'trusted_proxies' =>
array (
0 => '172.18.0.1', // Nginx 프록시의 IP 주소
),
'overwrite.cli.url' => 'https://nextcloud.example.com',
'overwritehost' => 'nextcloud.example.com',
'overwriteprotocol' => 'https',
'overwritewebroot' => '/',
//... 기타 설정들...
);

4. 배포 모델 II: 올인원(AIO) 스택

이 섹션에서는 설치 및 유지보수의 용이성을 우선시하는 사용자를 위해 공식 AIO 모델을 배포하는 방법을 안내합니다.

4.1 AIO 마스터 컨테이너 초기화

AIO 배포는 모든 것을 관리하는 단일 ‘마스터’ 컨테이너를 시작하는 것으로 시작됩니다. 리버스 프록시 환경에서는 외부 트래픽을 프록시가 처리하므로, AIO 컨테이너의 80 및 8443 포트를 호스트에 직접 노출할 필요가 없습니다. 다음은 리버스 프록시 환경에 최적화된 docker run 명령입니다.5

Bash

sudo docker run \
--init \
--sig-proxy=false \
--name nextcloud-aio-mastercontainer \
--restart always \
--publish 8080:8080 \
-e APACHE_PORT=11000 \
-v nextcloud_aio_mastercontainer:/mnt/docker-aio-config \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
nextcloud/all-in-one:latest

--publish 8080:8080: 초기 설정을 위한 AIO 관리 인터페이스 포트입니다.
-e APACHE_PORT=11000: AIO가 내부적으로 생성할 Nextcloud용 Apache 컨테이너가 사용할 포트를 지정합니다. 이 포트로 리버스 프록시를 설정하게 됩니다.
-v nextcloud_aio_mastercontainer...: AIO 설정 데이터의 영속성을 위한 볼륨입니다.
-v /var/run/docker.sock...: 마스터 컨테이너가 다른 Docker 컨테이너를 관리하기 위해 Docker 소켓에 읽기 전용으로 접근할 수 있도록 허용합니다.

4.2 AIO를 위한 Nginx 구성

AIO의 Nginx 구성은 마이크로서비스 모델과 유사하지만, proxy_pass 대상이 다릅니다. 특히, AIO의 설치 과정은 여러 단계로 이루어지므로 프록시 설정에 주의가 필요합니다.

최종적으로 사용할 Nginx 설정은 다음과 같습니다. proxy_pass는 AIO 마스터 컨테이너 실행 시 -e APACHE_PORT로 지정한 포트(이 예시에서는 11000)를 가리켜야 합니다.13

Nginx

server {
listen 443 ssl http2;
server_name nextcloud.example.com;

#... SSL 및 보안 헤더 설정은 마이크로서비스 섹션과 동일...

location / {
proxy_pass http://127.0.0.1:11000; # AIO의 Apache 컨테이너 포트
#... 프록시 헤더 설정은 마이크로서비스 섹션과 동일...
client_max_body_size 10G;
}

#... CalDAV/CardDAV 설정은 마이크로서비스 섹션과 동일...
}

4.3 AIO 부트스트래핑 과정과 프록시의 복잡성

AIO의 설치 과정은 단일 단계가 아닌, 리버스 프록시의 대상이 변경되어야 하는 다단계 부트스트랩 프로세스입니다. 이 점이 마이크로서비스 모델과의 가장 큰 차이점이며, 사용자가 가장 흔하게 겪는 문제의 원인이 됩니다.

1단계 (마스터 컨테이너 인터페이스 접속): AIO 마스터 컨테이너가 시작되면, 포트 8080에서 웹 기반 관리 인터페이스를 제공합니다.5 초기 설정을 진행하려면 이 인터페이스에 접속해야 합니다.
2단계 (도메인 검증): 사용자가 관리 인터페이스에서 자신의 도메인(예: nextcloud.example.com)을 입력하면, AIO는 해당 도메인이 서버를 올바르게 가리키는지 확인하기 위해 nextcloud-aio-domaincheck라는 임시 컨테이너를 실행합니다.13
3단계 (메인 컨테이너 실행): 도메인 검증이 성공적으로 완료되면, 임시 컨테이너는 종료되고 실제 Nextcloud 서비스를 제공할 nextcloud-aio-apache 컨테이너가 시작됩니다. 이 컨테이너는 앞서 지정한 포트(예: 11000)에서 수신 대기합니다.13

이 과정에서 발생하는 문제는 명확합니다. 만약 처음부터 Nginx 프록시를 최종 목적지인 127.0.0.1:11000으로 설정하면, 2단계의 도메인 검증이 실패합니다. 왜냐하면 아직 해당 포트에서 수신 대기하는 컨테이너가 없기 때문입니다. 반대로 프록시를 127.0.0.1:8080으로 설정하면 초기 설정은 가능하지만, 설정 완료 후 실제 Nextcloud 인스턴스에는 접속할 수 없습니다.

따라서, AIO를 리버스 프록시와 함께 성공적으로 설치하려면 다음의 2단계 절차를 따라야 합니다.

설치 단계: https://<서버_IP>:8080으로 직접 접속하거나, 임시로 Nginx 프록시를 127.0.0.1:8080으로 설정하여 AIO 설정 마법사를 완료합니다.
운영 단계: AIO 관리 인터페이스에서 모든 컨테이너가 성공적으로 실행되었음을 확인한 후, Nginx 프록시의 proxy_pass 대상을 최종 Apache 컨테이너 포트인 http://127.0.0.1:11000으로 영구적으로 변경합니다.

4.4 AIO 웹 인터페이스 탐색

위의 프록시 설정 절차를 이해했다면, AIO 웹 인터페이스를 통한 설정은 간단합니다.

브라우저에서 https://<서버_IP>:8080에 접속하여 화면에 표시되는 초기 비밀번호를 복사합니다.
해당 비밀번호로 로그인한 후, 사용할 공개 도메인 이름(예: nextcloud.example.com)을 입력합니다.
AIO가 도메인 검증을 수행합니다. (이 단계에서 문제가 발생하면 4.3 섹션을 다시 확인하십시오.)
Nextcloud Office, Talk 등 설치할 추가 컨테이너를 선택합니다.
’Start containers’를 클릭하고 모든 컨테이너의 설치 및 시작이 완료될 때까지 기다립니다.
설치가 완료되면 Nginx 구성을 최종 포트(11000)로 변경하고 Nginx를 다시 로드합니다. 이제 https://nextcloud.example.com으로 Nextcloud에 접속할 수 있습니다.

5. 배포 후 운영 및 고급 주제

5.1 업데이트 및 유지보수 절차

마이크로서비스 스택: 표준 Docker Compose 워크플로우를 따릅니다. docker compose pull 명령으로 최신 이미지를 가져온 후, docker compose up -d 명령으로 컨테이너를 재생성하여 업데이트를 적용합니다.10 업데이트 전에는 항상 릴리스 노트를 확인하여 주요 변경 사항이 있는지 확인하는 것이 중요합니다.
AIO 스택: 모든 업데이트는 AIO 웹 관리 인터페이스를 통해 관리됩니다. 인터페이스는 모든 관리 대상 컨테이너에 대한 원클릭 업데이트 프로세스를 제공하며, 이는 AIO 모델의 주요 장점 중 하나입니다.5

5.2 `occ`를 이용한 명령줄 관리

Nextcloud는 occ라는 강력한 명령줄 도구를 제공하여 다양한 관리 작업을 수행할 수 있습니다. Docker 환경에서 occ를 실행하려면 다음 명령을 사용합니다. --user www-data 옵션은 올바른 파일 권한으로 명령을 실행하기 위해 필수적입니다.8

Bash

# 마이크로서비스 스택의 경우
docker compose exec --user www-data app php occ <명령>

# 예시: 모든 파일 스캔
docker compose exec --user www-data app php occ files:scan --all

# 예시: 유지보수 모드 활성화
docker compose exec --user www-data app php occ maintenance:mode --on

5.3 일반적인 통합 문제 해결

502 Bad Gateway: 이 오류는 일반적으로 Nginx가 업스트림 애플리케이션 컨테이너에 연결할 수 없을 때 발생합니다. 컨테이너가 실행 중이지 않거나, proxy_pass 주소/포트가 잘못되었거나, Docker 네트워크 설정이 잘못된 경우에 발생할 수 있습니다.12
리디렉션 루프: config.php의 overwrite 매개변수가 잘못 설정되었거나, X-Forwarded-Proto 헤더가 충돌하여 Nextcloud가 HTTP에서 HTTPS로 계속해서 리디렉션을 시도할 때 발생합니다.14
볼륨 권한 오류: Named Volume 대신 호스트의 디렉터리를 바인드 마운트하여 사용하는 경우, 호스트 시스템의 파일 소유권 및 권한 문제로 인해 오류가 발생할 수 있습니다. 컨테이너 내부의 www-data 사용자(UID 33)가 해당 디렉터리에 대한 읽기/쓰기 권한을 가지고 있는지 확인해야 합니다.
AIO 도메인 검증 실패: 이 문제의 가장 흔한 원인은 4.3 섹션에서 설명한 바와 같이, Nginx 프록시가 설치 과정의 올바른 단계에서 올바른 컨테이너/포트를 가리키고 있지 않기 때문입니다.

6. 결론

본 보고서는 Docker Compose와 Nginx 리버스 프록시를 사용하여 Nextcloud Hub를 배포하는 두 가지 주요 아키텍처인 마이크로서비스 스택과 올인원(AIO) 스택을 상세히 분석했습니다. 각 모델은 서로 다른 운영 철학을 가지고 있으며, 사용자의 기술 수준과 요구사항에 따라 선택이 달라져야 합니다.

최종적으로 다음과 같은 기준에 따라 아키텍처를 선택할 것을 권장합니다.

마이크로서비스 스택을 선택해야 하는 경우:
각 구성 요소(데이터베이스, 캐시 등)에 대한 세분화된 제어가 필요한 경우.
기존에 운영 중인 외부 데이터베이스나 캐시와 통합해야 하는 경우.
환경을 광범위하게 사용자 정의하고 최적화할 필요가 있는 전문가.
올인원(AIO) 스택을 선택해야 하는 경우:
설치 및 유지보수의 용이성을 최우선으로 생각하는 경우.
최소한의 설정으로 Nextcloud Hub의 모든 기능(Office, Talk 등)을 즉시 사용하고 싶은 경우.
관리 부담이 적은, 어플라이언스와 같은 안정적인 시스템을 선호하는 경우.

본 보고서에 기술된 지침과 구성을 정확히 따른다면, 어떤 경로를 선택하든 강력하고 안전한 자체 호스팅 클라우드 플랫폼을 성공적으로 구축할 수 있을 것입니다.

7. 참고 자료

Suggestion for the installation process in Docker Compose - Nextcloud community, https://help.nextcloud.com/t/suggestion-for-the-installation-process-in-docker-compose/190035
Docker image of Nextcloud - GitHub, https://github.com/nextcloud/docker
Deploy Nextcloud with Docker Compose | by Chris Grime - Medium, https://chrisgrime.medium.com/deploy-nextcloud-with-docker-compose-935a76a5eb78
Setup nextcloud using docker-compose with postgres in a few simple steps - GitHub, https://github.com/ezy/nextcloud-pg-docker
nextcloud/all-in-one: The official Nextcloud installation method. Provides easy deployment and maintenance with most features included in this one Nextcloud instance. - GitHub, https://github.com/nextcloud/all-in-one
How to Install the Nextcloud All-in-One on Linux, https://nextcloud.com/blog/how-to-install-the-nextcloud-all-in-one-on-linux/
Nextcloud with nginx, docker compose (postgresql, redis), optimization - Reddit, https://www.reddit.com/r/NextCloud/comments/1f10hsa/nextcloud_with_nginx_docker_compose_postgresql/
nextcloud - Official Image - Docker Hub, https://hub.docker.com/_/nextcloud/
nextcloud - Official Image | Docker Hub, https://hub.docker.com/_/nextcloud
Running Nextcloud using Docker Compose - Pi My Life Up, https://pimylifeup.com/nextcloud-docker/
Reverse proxy — Nextcloud latest Administration Manual latest …, https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/reverse_proxy_configuration.html
NGINX configuration — Nextcloud latest Administration Manual …, https://docs.nextcloud.com/server/latest/admin_manual/installation/nginx.html
Guide: Setup - Nextcloud AIO and Nginx Proxy Manager #4240 - GitHub, https://github.com/nextcloud/all-in-one/discussions/4240
Nginx reverse proxy, what to write in nextcloud’s config.php? - ℹ️ Support, https://help.nextcloud.com/t/nginx-reverse-proxy-what-to-write-in-nextclouds-config-php/9149

Docker Compose 및 외부 Nginx 리버스 프록시를 활용한 프로덕션급 Nextcloud Hub 배포 안내서

1. 아키텍처 고려사항

1.1 목표 개요

1.2 배포 모델 분석: 마이크로서비스 vs. 올인원(AIO)

1.3 권장 스택 구성 요소

2. 배포 모델 I: 마이크로서비스 스택

2.1 디렉터리 구조 및 환경 설정

2.2 docker-compose.yml 구성 파일

2.3 설정의 생명주기:.env 파일과 config.php의 관계

2.4 스택 초기화 및 검증

3. Nginx 리버스 프록시 및 애플리케이션 통합

3.1 Nginx server 블록 구성

3.2 다층적 파일 업로드 제한 설정

3.3 CalDAV/CardDAV 서비스 검색

3.4 Nextcloud의 프록시 설정 최종화 (config.php)

4. 배포 모델 II: 올인원(AIO) 스택

4.1 AIO 마스터 컨테이너 초기화

4.2 AIO를 위한 Nginx 구성

4.3 AIO 부트스트래핑 과정과 프록시의 복잡성

4.4 AIO 웹 인터페이스 탐색

5. 배포 후 운영 및 고급 주제

5.1 업데이트 및 유지보수 절차

5.2 occ를 이용한 명령줄 관리

5.3 일반적인 통합 문제 해결

6. 결론

7. 참고 자료

3.1 Nginx `server` 블록 구성

5.2 `occ`를 이용한 명령줄 관리